//
// Copyright (c) 2002-2010 "Neo Technology,"
//     Network Engine for Objects in Lund AB [http://neotechnology.com]
// *
// This file is part of Neo4j.
// 
// Neo4j is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
// 
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
// 
namespace org.neo4j.graphdb
{
    ///
    /// <summary>
    ///  A programmatically handled transaction. <em>All operations that work with the
    /// node space - even read operations - must be wrapped in a transaction.</em>
    /// Transactions are thread confined. Transactions can either be handled
    /// programmatically, through this interface, or by a container through the Java
    /// Transaction API (JTA). The Transaction interface makes handling programmatic
    /// transactions easier than using JTA programmatically. Here's the idiomatic use
    /// of programmatic transactions in Neo4j:
    /// 
    /// <pre>
    /// <code>
    /// Transaction tx = graphDb.beginTx();
    /// try
    /// {
    /// 	... // any operation that works with the node space
    ///tx.success();
    /// }
    /// finally
    /// {
    ///tx.finish();
    /// }
    /// </code>
    /// </pre>
    /// <p>
    /// Let's walk through this example line by line. First we retrieve a Transaction
    /// object by invoking the <seealso cref="GraphDatabaseService#beginTx()"/> factory method.
    /// This creates a new Transaction instance which has internal state to keep
    /// track of whether the current transaction is successful. Then we wrap all
    /// operations that work with the node space in a try-finally block. At the end
    /// of the block, we invoke the <seealso cref="Finish() tx.Success()"/> method to indicate
    /// that the transaction is successful. As we exit the block, the finally clause
    /// will kick in and <seealso cref="Finish() tx.Finish"/> will commit the transaction if
    /// the internal state indicates success or else mark it for rollback.
    /// </p>
    /// If an exception is raised in the try-block, <seealso cref="Success()"/> will never be
    /// invoked and the internal state of the transaction object will cause
    /// <seealso cref="Finish()"/> to roll back the transaction. This is very important:
    /// unless <seealso cref="Success()"/> is invoked, the transaction will fail upon
    /// <seealso cref="Finish()"/>. A transaction can be explicitly marked for rollback by
    /// invoking the <seealso cref="Failure()"/> method.
    ///  </summary> 
    public interface Transaction
    {
        ///<summary> 
        /// Marks this transaction as failed, which means that it will
        ///unconditionally be rolled back when <seealso cref="Finish()"/> is called. Once
        ///this method has been invoked, it doesn't matter how many times
        ///<seealso cref="Success()"/> is invoked -- the transaction will still be rolled
        ///back.
        ///  </summary>
        void Failure();
        ///<summary>
        ///  Marks this transaction as successful, which means that it will be
        ///commited upon invocation of <seealso cref="Finish()"/> unless <seealso cref="Failure()"/>
        ///has or will be invoked before then. </summary>
        void Success();
        ///<summary>
        ///  Commits or marks this transaction for rollback, depending on whether
        ///<seealso cref="Success()"/> or <seealso cref="Failure()"/> has been previously invoked. </summary>
        void Finish();
    }
}